.TH "gdal_grid" 1 "Mon Apr 25 2016" "GDAL" \" -*- nroff -*-
.ad l
.nh
.SH NAME
gdal_grid \- gdal_grid 
creates regular grid from the scattered data
.SH "SYNOPSIS"
.PP
.PP
.nf
gdal_grid [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
          CInt16/CInt32/CFloat32/CFloat64}]
          [-of format] [-co "NAME=VALUE"]
          [-zfield field_name] [-z_increase increase_value] [-z_multiply multiply_value]
          [-a_srs srs_def] [-spat xmin ymin xmax ymax]
          [-clipsrc <xmin ymin xmax ymax>|WKT|datasource|spat_extent]
          [-clipsrcsql sql_statement] [-clipsrclayer layer]
          [-clipsrcwhere expression]
          [-l layername]* [-where expression] [-sql select_statement]
          [-txe xmin xmax] [-tye ymin ymax] [-outsize xsize ysize]
          [-a algorithm[:parameter1=value1]*] [-q]
          <src_datasource> <dst_filename>
.fi
.PP
.SH "DESCRIPTION"
.PP
This program creates regular grid (raster) from the scattered data read from the OGR datasource\&. Input data will be interpolated to fill grid nodes with values, you can choose from various interpolation methods\&.
.PP
Starting with GDAL 1\&.10, it is possible to set the \fBGDAL_NUM_THREADS\fP configuration option to parallelize the processing\&. The value to specify is the number of worker threads, or \fIALL_CPUS\fP to use all the cores/CPUs of the computer\&.
.PP
.IP "\fB\fB-ot\fP \fItype\fP:\fP" 1c
For the output bands to be of the indicated data type\&.
.PP
.IP "\fB\fB-of\fP \fIformat\fP:\fP" 1c
Select the output format\&. The default is GeoTIFF (GTiff)\&. Use the short format name\&.
.PP
.IP "\fB\fB-txe\fP \fIxmin xmax\fP:\fP" 1c
Set georeferenced X extents of output file to be created\&.
.PP
.IP "\fB\fB-tye\fP \fIymin ymax\fP:\fP" 1c
Set georeferenced Y extents of output file to be created\&.
.PP
.IP "\fB\fB-outsize\fP \fIxsize ysize\fP:\fP" 1c
Set the size of the output file in pixels and lines\&.
.PP
.IP "\fB\fB-a_srs\fP \fIsrs_def\fP:\fP" 1c
Override the projection for the output file\&. The \fIsrs_def\fP may be any of the usual GDAL/OGR forms, complete WKT, PROJ\&.4, EPSG:n or a file containing the WKT\&. 
.PP
.IP "\fB\fB-zfield\fP \fIfield_name\fP:\fP" 1c
Identifies an attribute field on the features to be used to get a Z value from\&. This value overrides Z value read from feature geometry record (naturally, if you have a Z value in geometry, otherwise you have no choice and should specify a field name containing Z value)\&.
.PP
.IP "\fB\fB-z_increase\fP \fIincrease_value\fP:\fP" 1c
Addition to the attribute field on the features to be used to get a Z value from\&. The addition should be the same unit as Z value\&. The result value will be Z value + Z increase value\&. The default value is 0\&.
.PP
.IP "\fB\fB-z_multiply\fP \fImultiply_value\fP:\fP" 1c
This is multiplication ratio for Z field\&. This can be used for shift from e\&.g\&. foot to meters or from elevation to deep\&. The result value will be (Z value + Z increase value) * Z multiply value\&. The default value is 1\&.
.PP
.IP "\fB\fB-a\fP \fI[algorithm[:parameter1=value1][:parameter2=value2]\&.\&.\&.]\fP: \fP" 1c
Set the interpolation algorithm or data metric name and (optionally) its parameters\&. See \fBINTERPOLATION ALGORITHMS\fP and \fBDATA METRICS\fP sections for further discussion of available options\&.
.PP
.IP "\fB\fB-spat\fP \fIxmin ymin xmax ymax\fP:\fP" 1c
Adds a spatial filter to select only features contained within the bounding box described by (xmin, ymin) - (xmax, ymax)\&.
.PP
.IP "\fB\fB-clipsrc\fP\fI [xmin ymin xmax ymax]|WKT|datasource|spat_extent\fP: \fP" 1c
Adds a spatial filter to select only features contained within the specified bounding box (expressed in source SRS), WKT geometry (POLYGON or MULTIPOLYGON), from a datasource or to the spatial extent of the \fB-spat\fP option if you use the \fIspat_extent\fP keyword\&. When specifying a datasource, you will generally want to use it in combination of the \fB-clipsrclayer\fP, \fB-clipsrcwhere\fP or \fB-clipsrcsql\fP options\&.
.PP
.IP "\fB\fB-clipsrcsql\fP \fIsql_statement\fP:\fP" 1c
Select desired geometries using an SQL query instead\&.
.PP
.IP "\fB\fB-clipsrclayer\fP \fIlayername\fP:\fP" 1c
Select the named layer from the source clip datasource\&.
.PP
.IP "\fB\fB-clipsrcwhere\fP \fIexpression\fP:\fP" 1c
Restrict desired geometries based on attribute query\&.
.PP
.IP "\fB\fB-l\fP \fIlayername\fP: \fP" 1c
Indicates the layer(s) from the datasource that will be used for input features\&. May be specified multiple times, but at least one layer name or a \fB-sql\fP option must be specified\&.
.PP
.IP "\fB\fB-where\fP \fIexpression\fP: \fP" 1c
An optional SQL WHERE style query expression to be applied to select features to process from the input layer(s)\&. 
.PP
.IP "\fB\fB-sql\fP \fIselect_statement\fP: \fP" 1c
An SQL statement to be evaluated against the datasource to produce a virtual layer of features to be processed\&.
.PP
.IP "\fB\fB-co\fP \fI'NAME=VALUE'\fP:\fP" 1c
Passes a creation option to the output format driver\&. Multiple \fB-co\fP options may be listed\&. See format specific documentation for legal creation options for each format\&.
.PP
.IP "\fB\fB-q\fP:\fP" 1c
Suppress progress monitor and other non-error output\&.
.PP
.IP "\fB\fIsrc_datasource\fP: \fP" 1c
Any OGR supported readable datasource\&.
.PP
.IP "\fB\fIdst_filename\fP: \fP" 1c
The GDAL supported output file\&.
.PP
.PP
.SH "INTERPOLATION ALGORITHMS"
.PP
There are number of interpolation algorithms to choose from\&.
.SS "invdist"
Inverse distance to a power\&. This is default algorithm\&. It has following parameters:
.PP
.IP "\fB\fIpower\fP: \fP" 1c
Weighting power (default 2\&.0)\&. 
.IP "\fB\fIsmoothing\fP: \fP" 1c
Smoothing parameter (default 0\&.0)\&. 
.IP "\fB\fIradius1\fP: \fP" 1c
The first radius (X axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIradius2\fP: \fP" 1c
The second radius (Y axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIangle\fP: \fP" 1c
Angle of search ellipse rotation in degrees (counter clockwise, default 0\&.0)\&. 
.IP "\fB\fImax_points\fP: \fP" 1c
Maximum number of data points to use\&. Do not search for more points than this number\&. This is only used if search ellipse is set (both radii are non-zero)\&. Zero means that all found points should be used\&. Default is 0\&. 
.IP "\fB\fImin_points\fP: \fP" 1c
Minimum number of data points to use\&. If less amount of points found the grid node considered empty and will be filled with NODATA marker\&. This is only used if search ellipse is set (both radii are non-zero)\&. Default is 0\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&. 
.PP
.SS "invdistnn"
(Since GDAL 2\&.1) Inverse distance to a power with nearest neighbor searching, ideal when max_points is used\&. It has following parameters:
.PP
.IP "\fB\fIpower\fP: \fP" 1c
Weighting power (default 2\&.0)\&. 
.IP "\fB\fIradius\fP: \fP" 1c
The radius of the search circle, which should be non-zero\&. Default is 1\&.0\&. 
.IP "\fB\fImax_points\fP: \fP" 1c
Maximum number of data points to use\&. Do not search for more points than this number\&. Found points will be ranked from nearest to furthest distance when weighting\&. Default is 12\&. 
.IP "\fB\fImin_points\fP: \fP" 1c
Minimum number of data points to use\&. If less amount of points found the grid node is considered empty and will be filled with NODATA marker\&. Default is 0\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&. 
.PP
.SS "average"
Moving average algorithm\&. It has following parameters:
.PP
.IP "\fB\fIradius1\fP: \fP" 1c
The first radius (X axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIradius2\fP: \fP" 1c
The second radius (Y axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIangle\fP: \fP" 1c
Angle of search ellipse rotation in degrees (counter clockwise, default 0\&.0)\&. 
.IP "\fB\fImin_points\fP: \fP" 1c
Minimum number of data points to use\&. If less amount of points found the grid node considered empty and will be filled with NODATA marker\&. Default is 0\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&. 
.PP
.PP
Note, that it is essential to set search ellipse for moving average method\&. It is a window that will be averaged when computing grid nodes values\&.
.SS "nearest"
Nearest neighbor algorithm\&. It has following parameters:
.PP
.IP "\fB\fIradius1\fP: \fP" 1c
The first radius (X axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIradius2\fP: \fP" 1c
The second radius (Y axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIangle\fP: \fP" 1c
Angle of search ellipse rotation in degrees (counter clockwise, default 0\&.0)\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&. 
.PP
.SS "linear"
(Since GDAL 2\&.1) Linear interpolation algorithm\&.
.PP
The Linear method performs linear interpolation by computing a Delaunay triangulation of the point cloud, finding in which triangle of the triangulation the point is, and by doing linear interpolation from its barycentric coordinates within the triangle\&. If the point is not in any triangle, depending on the radius, the algorithm will use the value of the nearest point or the nodata value\&.
.PP
It has following parameters:
.PP
.IP "\fB\fIradius\fP: \fP" 1c
In case the point to be interpolated does not fit into a triangle of the Delaunay triangulation, use that maximum distance to search a nearest neighbour, or use nodata otherwise\&. If set to -1, the search distance is infinite\&. If set to 0, nodata value will be always used\&. Default is -1\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&. 
.PP
.SH "DATA METRICS"
.PP
Besides the interpolation functionality \fBgdal_grid\fP can be used to compute some data metrics using the specified window and output grid geometry\&. These metrics are:
.PP
.IP "\fB\fIminimum\fP: \fP" 1c
Minimum value found in grid node search ellipse\&.
.PP
.IP "\fB\fImaximum\fP: \fP" 1c
Maximum value found in grid node search ellipse\&.
.PP
.IP "\fB\fIrange\fP: \fP" 1c
A difference between the minimum and maximum values found in grid node search ellipse\&.
.PP
.IP "\fB\fIcount\fP: \fP" 1c
A number of data points found in grid node search ellipse\&.
.PP
.IP "\fB\fIaverage_distance\fP: \fP" 1c
An average distance between the grid node (center of the search ellipse) and all of the data points found in grid node search ellipse\&.
.PP
.IP "\fB\fIaverage_distance_pts\fP: \fP" 1c
An average distance between the data points found in grid node search ellipse\&. The distance between each pair of points within ellipse is calculated and average of all distances is set as a grid node value\&.
.PP
.PP
.PP
All the metrics have the same set of options:
.PP
.IP "\fB\fIradius1\fP: \fP" 1c
The first radius (X axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIradius2\fP: \fP" 1c
The second radius (Y axis if rotation angle is 0) of search ellipse\&. Set this parameter to zero to use whole point array\&. Default is 0\&.0\&. 
.IP "\fB\fIangle\fP: \fP" 1c
Angle of search ellipse rotation in degrees (counter clockwise, default 0\&.0)\&. 
.IP "\fB\fImin_points\fP: \fP" 1c
Minimum number of data points to use\&. If less amount of points found the grid node considered empty and will be filled with NODATA marker\&. This is only used if search ellipse is set (both radii are non-zero)\&. Default is 0\&. 
.IP "\fB\fInodata\fP: \fP" 1c
NODATA marker to fill empty points (default 0\&.0)\&.
.PP
.PP
.SH "READING COMMA SEPARATED VALUES"
.PP
Often you have a text file with a list of comma separated XYZ values to work with (so called CSV file)\&. You can easily use that kind of data source in \fBgdal_grid\fP\&. All you need is create a virtual dataset header (VRT) for you CSV file and use it as input datasource for \fBgdal_grid\fP\&. You can find details on VRT format at \fCVirtual Format\fP description page\&.
.PP
Here is a small example\&. Let we have a CSV file called \fIdem\&.csv\fP containing
.PP
.PP
.nf
Easting,Northing,Elevation
86943.4,891957,139.13
87124.3,892075,135.01
86962.4,892321,182.04
87077.6,891995,135.01
...
.fi
.PP
.PP
For above data we will create \fIdem\&.vrt\fP header with the following content:
.PP
.PP
.nf
<OGRVRTDataSource>
    <OGRVRTLayer name="dem">
        <SrcDataSource>dem.csv</SrcDataSource> 
        <GeometryType>wkbPoint</GeometryType> 
        <GeometryField encoding="PointFromColumns" x="Easting" y="Northing" z="Elevation"/> 
    </OGRVRTLayer>
</OGRVRTDataSource>
.fi
.PP
.PP
This description specifies so called 2\&.5D geometry with three coordinates X, Y and Z\&. Z value will be used for interpolation\&. Now you can use \fIdem\&.vrt\fP with all OGR programs (start with \fBogrinfo\fP to test that everything works fine)\&. The datasource will contain single layer called \fI'dem'\fP filled with point features constructed from values in CSV file\&. Using this technique you can handle CSV files with more than three columns, switch columns, etc\&.
.PP
If your CSV file does not contain column headers then it can be handled in the following way:
.PP
.PP
.nf
<GeometryField encoding="PointFromColumns" x="field_1" y="field_2" z="field_3"/>
.fi
.PP
.PP
\fCComma Separated Value\fP description page contains details on CSV format supported by GDAL/OGR\&.
.SH "C API"
.PP
Starting with GDAL 2\&.1, this utility is also callable from C with GDALGrid()\&.
.SH "EXAMPLE"
.PP
The following would create raster TIFF file from VRT datasource described in \fBREADING COMMA SEPARATED VALUES\fP section using the inverse distance to a power method\&. Values to interpolate will be read from Z value of geometry record\&.
.PP
.PP
.nf
gdal_grid -a invdist:power=2.0:smoothing=1.0 -txe 85000 89000 -tye 894000 890000 -outsize 400 400 -of GTiff -ot Float64 -l dem dem.vrt dem.tiff
.fi
.PP
.PP
The next command does the same thing as the previous one, but reads values to interpolate from the attribute field specified with \fB-zfield\fP option instead of geometry record\&. So in this case X and Y coordinates are being taken from geometry and Z is being taken from the \fI'Elevation'\fP field\&. The GDAL_NUM_THREADS is also set to parallelize the computation\&.
.PP
.PP
.nf
gdal_grid -zfield "Elevation" -a invdist:power=2.0:smoothing=1.0 -txe 85000 89000 -tye 894000 890000 -outsize 400 400 -of GTiff -ot Float64 -l dem dem.vrt dem.tiff --config GDAL_NUM_THREADS ALL_CPUS
.fi
.PP
.SH "AUTHORS"
.PP
Andrey Kiselev dron@ak4719.spb.edu 
